Android SDK使用指南

本指南将会为您介绍如何使用Android SDK接入您的项目，如果您想获得API接口的详细说明，可以查看Android SDK API文档。您可以在访问GitHub获取Android SDK的源代码。

最新版本为：2.2.2

更新时间为：2019-12-04

1.初始化SDK

1.1 自动集成Android SDK

a) 使用Gradle集成

使用Android Studio，在 app 目录下的 build.gradle 文件中添加依赖项，将会自动完成SDK集成：

请注意，2.1.0 版本更换了包名，老的包名同时可以使用，但后续不会又新特性的更新，请从老版本升级至新版本时注意调整包名

dependencies {
    implementation 'cn.thinkingdata.android:ThinkingAnalyticsSDK:2.2.2'
}

b) 使用集成自动采集功能（可选）

如果需要使用自动采集功能（控件点击事件和 Fragment 浏览事件），请添加自动采集插件（可选）:

apply plugin: 'cn.thinkingdata.android'

buildscript {
    repositories {
        google()
        jcenter()
    }
    dependencies {
        classpath 'cn.thinkingdata.android:android-gradle-plugin:2.0.1'
    }
}

1.2 手动集成

由于依赖包问题，手动集成暂不支持自动采集功能，请下载下方链接中的SDK

SDK版本：1.3.0

下载地址

1.2.1 使用Android Studio手动集成

1.下载最新版SDK文件，解压压缩包

2.刚刚解压的 jar 文件拖入项目的 libs 文件夹内

3.右键 jar 文件，点击 Add As Library... 选项，将 SDK 文件置入对应项目，即可完成SDK集成

1.2.2 使用Eclipse手动集成

1.下载最新版SDK文件，解压压缩包

2.在Eclipse中右键项目根目录，选择Properties

3.选择Java Build Path，切换到Libraries标签页，点击Add External JARs...，再选择刚刚解压的 jar 文件，将 SDK 文件置入项目，即可完成SDK集成

1.3 初始化SDK

在1.3.0版本中，新增多APP ID实例的特性，添加了一种新的初始化方式，关于多APPID的使用指南，请参考Android SDK 多APPID指南一节

在应用程序的 Application 类的 onCreate 方法中调用

  ThinkingAnalyticsSDK instance = ThinkingAnalyticsSDK.sharedInstance(mContext, TA_APP_ID, TA_SERVER_URL);

  // 后续可以通过如下两种方法使用 SDK
  instance.track("someevent");
  ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID).track("some_event");


  // 1.3.0之前，或者单实例可使用下列方法初始化与使用 SDK
  // ThinkingAnalyticsSDK.sharedInstance(TA_APP_ID, TA_SERVER_URL);
  // ThinkingAnalyticsSDK.sharedInstance(this).track("some_event");

参数TA_APP_ID是您的项目的APP_ID，在您申请项目时会给出，请在此处填入

参数TA_SERVER_URL为数据上传的URL

如果您使用的是云服务，请输入以下URL:

https://receiver.ta.thinkingdata.cn

如果您使用的是私有化部署的版本，请为数据采集地址配置HTTPS证书，并使用以下URL:

https://数据采集地址绑定域名

a) 开启与 H5 页面的打通（可选）

如果需要与采集 H5 页面数据的JavaScript SDK进行打通，在初始化 WebView 时调用如下接口，详情请参考H5 与 APP SDK 打通一节

//打通H5页面数据
  instance.setJsBridge(webView);
// ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID).setJsBridge(webView);

//单实例的调用方法
// ThinkingAnalyticsSDK.sharedInstance(this).setJsBridge(webView);

2.设置用户ID

在使用SDK之后，SDK会使用UUID作为每个用户的默认访客ID，该ID将会作为用户在未登录状态下身份识别ID。需要注意的是，UUID在用户重新安装APP以及更换设备时将会变更。

a) 设置访客ID（可选）

如果您的App对每个用户有自己的访客ID管理体系，则您可以调用identify来设置访客ID：

instance.identify("123456789ABCabc");

如果需要获得访客ID，可以调用getDistinctId获取：

//返回访客ID，多实例的情况下，返回的是调用实例的访客ID
String distinctId = instance.getDistinctId();

b) 设置账号ID

在用户进行登录时，可调用login来设置用户的账号ID，在设置完账号ID后，将会以账号ID作为身份识别ID，并且设置的账号ID将会在调用logout之前一直保留：

instance.login("[email protected]");

login可以多次调用，每次调用会判断传入的账号ID与先前保存的ID是否一致，一致则忽略调用，不一致则会覆盖先前的ID。

请注意，该方法不会上传用户登录的事件

c) 清除账号ID

在用户产生登出行为之后，可调用logout来清除账号ID，在下次调用login之前，将会以访客ID作为身份识别ID：

instance.logout();

我们推荐您在显性的登出事件时调用logout，比如用户产生了注销账号这一行为时才调用，而不需要在关闭App时调用。

请注意，该方法不会上传用户登出的事件

3.发送事件

在SDK初始化完成之后，您就可以调用track来上传事件，一般情况下，您可能需要上传十几到上百个不同的事件，如果您是第一次使用TDA后台，我们推荐您先上传几个关键事件。

a)发送事件

您可以调用track来上传事件，建议您根据先前梳理的文档来设置事件的属性以及发送信息的条件，此处以用户购买某商品作为范例：

//商店购买事件
try {
    JSONObject properties = new JSONObject();
    properties.put("product_name","商品名");
    properties.put("product_num",1); 
    properties.put("Cost",100);  
    properties.put("isFirstBuy",true);
    instance.track("product_buy",properties);
} catch (JSONException e) {
    e.printStackTrace();
}

事件的名称是String类型，只能以字母开头，可包含数字，字母和下划线“_”，长度最大为50个字符，对字母大小写不敏感。

• 事件的属性是一个JSONObject对象，其中每个元素代表一个属性。
• Key的值为属性的名称，为String类型，规定只能以字母开头，包含数字，字母和下划线“_”，长度最大为50个字符，对字母大小写不敏感。
• Value为该属性的值，支持String、Number、Boolean和Date。

在2.2.0版本中加入了设置事件触发时间及时间偏移的方法重载，支持传入Date类型的参数来设置事件触发时间，以TimeZone类型的参数来设置时间偏移。不传入该参数，则取track被调用时的本机时间以及偏移作为事件触发时间以及时区偏移：

try {
    JSONObject properties = new JSONObject();
    properties.put("product_name","商品名");
    properties.put("product_num",1);
    properties.put("Cost",100);
    properties.put("isFirstBuy",true);
    instance.track("product_buy", properties, new Date(), TimeZone.getDefault());
} catch (JSONException e) {
    e.printStackTrace();
}

另外，尽管事件可以设置触发时间，但是接收端会做如下的限制，只接收相对服务器时间在前10天至后3天的数据，超过时限的数据将会被视为异常数据，整条数据无法入库。

b)设置公共事件属性

对于一些重要的属性，譬如用户的会员等级、来源渠道等，这些属性需要设置在每个事件中，此时您可以将这些属性设置为公共事件属性。公共事件属性指的就是每个事件都会带有的属性，您可以调用setSuperProperties来设置公共事件属性，我们推荐您在发送事件前，先设置公共事件属性。

• 公共事件属性同样也是一个JSONObject对象，其中每个元素代表一个属性。
• Key的值为属性的名称，为String类型，规定只能以字母开头，包含数字，字母和下划线“_”，长度最大为50个字符，对字母大小写不敏感。
• Value为该属性的值，支持String、Number、Boolean和Date。

//设置公共事件属性
try {
    JSONObject superProperties = new JSONObject();
    superProperties.put("vip_level",2);
    superProperties.put("Channel","A1");
    instance.setSuperProperties(superProperties);
} catch (JSONException e) {
    e.printStackTrace();
}

//使用track上传事件，此时事件中会带有公共事件属性
try {
    JSONObject properties = new JSONObject();
    properties.put("product_id","A1354");
    instance.track("product_pay",properties);      
} catch (JSONException e) {
    e.printStackTrace();
}

//相当于在每个事件中加入这些属性
try {
    JSONObject properties = new JSONObject();
    properties.put("vip_level",2);
    properties.put("Channel","A1");
    properties.put("product_id","A1354");
    instance.track("product_pay",properties);      
} catch (JSONException e) {
    e.printStackTrace();
}

公共事件属性将会被保存到缓存中，无需每次启动App时调用。如果调用setSuperProperties上传了先前已设置过的公共事件属性，则会覆盖之前的属性。如果公共事件属性和track上传的某个属性的Key重复，则该事件的属性会覆盖公共事件属性：

//承接上个例子，此时的公共事件属性有"Channel"与"vip_level"
try {
    JSONObject superProperties = new JSONObject();
    superProperties.put("Channel","B1");        //"Channel"被覆盖
    instance.setSuperProperties(superProperties);
} catch (JSONException e) {
    e.printStackTrace();
}

try {
    JSONObject properties = new JSONObject();
    properties.put("product_id","A1354");
    properties.put("vip_level",3);            //"vip_level"被覆盖
    instance.track("product_pay",properties);      
} catch (JSONException e) {
    e.printStackTrace();
}

//收到的数据中属性"Channel"的值为"B1"，"vip_level"的值为3

如果您需要删除某个公共事件属性，您可以调用unsetSuperProperty清除其中一个公共事件属性；如果您想要清空所有公共事件属性，则可以调用clearSuperProperties。

//清除一条公共事件属性，比如将之前设置"Channel"属性清除，之后的数据将不会该属性
    instance.unsetSuperProperty("Channel");

//清除所有公共事件属性
    instance.clearSuperProperties();

c) 设置动态公共属性

在1.3.0版本中，新增了动态公共属性的特性，即公共属性可以上报时获取当时的值，使得诸如会员等级之类的可变公共属性可以被便捷地上报。通过setDynamicSuperPropertiesTracker设置动态公共属性类之后，SDK 将会在事件上报时自动获取 getDynamicSuperProperties 中的属性，并添加到触发的事件中。以下例子是每次上报时将时间加入到事件中，当事件触发时，就会将getDynamicSuperProperties的返回值加入到事件属性中。

// 设置动态公共属性，在事件上报时动态获取事件发生时刻
instance.setDynamicSuperPropertiesTracker(
    new ThinkingAnalyticsSDK.DynamicSuperPropertiesTracker() {   

        // 复写getDynamicSuperProperties来设置动态公共属性的属性值获取方法
        @Override
        public JSONObject getDynamicSuperProperties() {
            JSONObject dynamicSuperProperties = new JSONObject();
            String pattern = "yyyy-MM-dd HH:mm:ss.SSS";
            SimpleDateFormat sDateFormat = new SimpleDateFormat(pattern,Locale.CHINA);
            String timeString = sDateFormat.format(new Date());
            try {
                dynamicSuperProperties.put("dynamicTime", timeString);
            } catch (JSONException e) {
                e.printStackTrace();
            }
            return dynamicSuperProperties;
        }
    });

d) 记录事件时长

您可以调用timeEvent来开始计时，配置您想要计时的事件名称，当您上传该事件时，将会自动在您的事件属性中加入#duration这一属性来表示记录的时长，单位为秒。

try {
    //用户进入商品页面，开始计时，记录的事件为"Enter_Shop"
    instance.timeEvent("Enter_Shop");

    //设置事件属性，用户浏览的商品ID
    JSONObject properties = new JSONObject();
    properties.put("product_id","A1354");

    //上传事件，计时结束，"Enter_Shop"这一事件中将会带有表示事件时长的属性#duration
    instance.track("Enter_Shop",properties);
} catch (JSONException e) {
    e.printStackTrace();
}

4.用户属性

TA平台目前支持的用户属性设置接口为user_set、user_setOnce、user_add、user_unset、user_delete。

a)user_set

对于一般的用户属性，您可以调用user_set来进行设置，使用该接口上传的属性将会覆盖原有的属性值，如果之前不存在该用户属性，则会新建该用户属性，类型与传入属性的类型一致，此处以设置用户名为例：

try {
    JSONObject properties = new JSONObject();
    properties.put("UserName","ABC");
    instance.user_set(properties);
    //此时"UserName"为"ABC"

    JSONObject newProperties = new JSONObject();
    newProperties.put("UserName","abc");
    instance.user_set(newProperties);    
    //此时"UserName"为"abc"    

} catch (JSONException e) {
    e.printStackTrace();
}

• user_set设置的用户属性是一个JSONObject对象，其中每个元素代表一个属性。
• Key的值为属性的名称，为String类型，规定只能以字母开头，包含数字，字母和下划线“_”，长度最大为50个字符，对字母大小写不敏感。
• Value为该属性的值，支持String、Number、Boolean和Date。

b)user_setOnce

如果您要上传的用户属性只要设置一次，则可以调用user_setOnce来进行设置，当该属性之前已经有值的时候，将会忽略这条信息，以设置首次付费时间来为例：

try {
    JSONObject properties = new JSONObject();
    properties.put("FirstPaidTime","2018-01-01 01:23:45.678");
    instance.user_setOnce(properties);
    //此时"FirstPaidTime"为"2018-01-01 01:23:45.678"

    JSONObject newProperties = new JSONObject();
    newProperties.put("FirstPaidTime","2018-12-31 01:23:45.678");
    instance.user_setOnce(newProperties);    
    //此时"FirstPaidTime"仍然为"2018-01-01 01:23:45.678"   

} catch (JSONException e) {
    e.printStackTrace();
}

• user_setOnce设置的用户属性类型及限制条件与user_set一致。

c)user_add

当您要上传数值型的属性时，您可以调用user_add来对该属性进行累加操作，如果该属性还未被设置，则会赋值0后再进行计算，可传入负值，等同于相减操作。此处以累计付费金额为例：

try {
    JSONObject properties = new JSONObject();
    properties.put("TotalRevenue",30);
    instance.user_add(properties);
    //此时"TotalRevenue"为30

    JSONObject newProperties = new JSONObject();
    newProperties.put("TotalRevenue",648);
    instance.user_add(newProperties);    
    //此时"TotalRevenue"为678 

} catch (JSONException e) {
    e.printStackTrace();
}

• user_add设置的属性类型以及Key值的限制与user_set一致，但Value只允许Number。

d) user_unset

当您要清空用户的用户属性值时，您可以调用user_unset来对指定属性进行清空操作，如果该属性还未在集群中被创建，则user_unset不会创建该属性

// 重置单个用户属性
instance.user_unset("key1");

// 重置多个用户属性
instance.user_unset("key1", "key2", "key3");

// 重置多个用户属性，传入字符串数组
String[] keys = {"key1", "key2"};
instance.user_unset(keys);

• user_unset传入的参数是用户属性的属性名，类型是字符串或字符串数组，支持可变长参数的形式。

e) user_delete

如果您要删除某个用户，可以调用user_delete将这名用户删除，您将无法再查询该名用户的用户属性，但该用户产生的事件仍然可以被查询到。

instance.user_delete();

5. 自动采集事件(手动集成暂不支持此功能)

请注意，如需使用自动采集功能，请集成自动采集功能的相关依赖项，点此查看添加依赖代码

关于自动采集事件的具体使用方法，请参考Android SDK 自动采集指南一章。

6. SDK配置

a) 设置上传的网络条件

在默认情况下，SDK将会网络条件为在3G, 4G 及 Wifi时上传数据，您可以通过下列方法修改允许上传的网络条件：

//只在Wifi环境下上报数据
ThinkingAnalyticsSDK.sharedInstance().setNetworkType(NETWORKTYPE_WIFI);

//在3G, 4G 及 Wifi时上传数据, 默认设置
ThinkingAnalyticsSDK.sharedInstance().setNetworkType(NETWORKTYPE_DEFAULT);

//在2G, 3G, 4G 及 Wifi时上传数据
ThinkingAnalyticsSDK.sharedInstance().setNetworkType(NETWORKTYPE_ALL);

b) 打印上传数据Log

在1.1.7版本，加入了打印Log的功能，您可以在 AndroidManifest.xml 中的application标签中添加以下代码开启打印Log功能（默认是关闭的）：

<application...>
    .....
       <meta-data
            android:name="com.thinkingdata.analytics.android.EnableTrackLogging"
            android:value="true" />
</application>

在2.0.0版本，加入了打印Log的接口，您可以调用enableTrackLog来开启（默认是关闭的）：

ThinkingAnalyticsSDK.enableTrackLog(true);

c) 获取设备ID

在2.0.0版本，加入了获取设备ID（也就是预置属性#device_id）的接口，您可以通过调用getDeviceId来获取设备ID：

 instance.getDeviceId();
 //如果需要将设备ID设置成访客ID可以如下调用
 //instance.identify(instance.getDeviceId());

d) 暂停/停止数据上报

在2.1.0版本中，新增了停止SDK上报数据的功能，一共有两类停止SDK上报的接口：

1. 暂停SDK上报（enableTracking）

您可能希望在一些场景下，暂时停止SDK的数据采集以及上报，比如用户处于测试环境中、或者用户登录了一个测试账号，此时您可以调用下列接口，暂时停止SDK的上报。

您可以通过某一实例（包括主要实例以及轻实例）调用enableTracking，传入false来暂停SDK的上报，该实例已经设置的#distinct_id、#account_id、公共属性等将保留；该实例已经采集但还未上报成功的数据将继续尝试上报；后续该实例不能采集以及上报任何新数据、不能设置访客ID、账户ID以及公共属性等，但是可以读取该实例已经设置的公共属性和设备ID、访客ID、账号ID等信息。

实例的停止状态将会被保存在本地缓存，直到调用enableTracking、传入true，SDK实例将会重新恢复数据采集以及上报，需要注意轻实例因为不进行缓存，因此每次打开APP后，轻实例的暂停状态不会被保留，将重新开启上报。

// 暂停上报
instance.enableTracking(false);

// 恢复上报
instance.enableTracking(true);

1. 停止SDK上报（optOutTracking）

在一些特殊场景下，您可能需要完全停止SDK的功能，比如在适用GDPR的地区，用户选择不提供数据采集权限，则您可以调用如下接口完全关闭SDK的功能。

optOutTracking只能通过主要实例调用，与enableTracking的最大区别在于，其将会清空该实例的本地缓存，包括本实例的访客ID，账号ID，公共属性，以及未上报的数据队列。之后再关闭该实例的采集和上报功能。

// 停止上报，并重置本地缓存
instance.optOutTracking();

如果您希望关闭SDK功能的同时，删除该用户在TA集群中的用户数据，可以调用optOutTrackingAndDeleteUser，这将会在停止SDK实例的功能前，上报一条 user_del数据，以删除该用户的用户数据。

// 停止上报，并发送删除用户请求
instance.optOutTrackingAndDeleteUser();

实例的停止状态也将保存在本地缓存，直到调用optInTracking，后续可以继续上报，但此时相当于一个全新的实例

// 重新开启上报
instance.optInTracking();

7. 相关预置属性

7.1 所有事件带有的预置属性

以下预置属性，是Android SDK中所有事件（包括自动采集事件）都会带有的预置属性

7.2 自动采集事件的预置属性

以下预置属性，是各个自动采集事件中所特有的预置属性

• APP启动事件（ta_app_start）的预置属性

• APP关闭事件（ta_app_end）的预置属性

• APP浏览页面事件（ta_app_view）的预置属性

• APP控件点击事件（ta_app_click）的预置属性

• APP崩溃事件（ta_app_crash）的预置属性

7.3 其他预置属性

除了上述提到预置属性，还有部分预置属性需要调用对应接口才会被记录：

ChangeLog

v2.2.2 2019/11/04

• 修复当API level小于18（Android 4.3）时，退出异常

v2.2.0 2019/10/22

• 支持重置用户属性接口user_unset
• 新增track接口chognzai，支持按照指定时区上传事件数据
• 新增预制属性#zone_offset，单位为小时。 默认情况下会将本地时区的偏移上报到服务端，该时间偏移会受夏令时影响。满足如下公式：

  utc_time + #zone_offset = #event_time
  

v2.1.0 2019/08/31

• 支持轻量级实例, 便于上报被动事件等需求
• 新增 enableTracking 接口, 可以打开或关闭实例上报功能
• 新增 optOutTracking/optInTracking 接口
• 优化上报逻辑，改进上报的频率和时效性
• 其他一些小的改进点

v2.0.1 2019/07/12

• 支持 H5 与自动采集事件新增APP安装事件

v2.0.0 2019/07/10

• 重构自动采集逻辑（需要配合 2.0 版本的插件编译）：
  • 去除 SDK 的第三方库依赖
  • Fragment 浏览事件不再需要继承 BaseFragment, 并加注解
  • 新增 TimePicker，DatePicker 等控件的点击事件采集
• 新增 getDeviceId() 接口
• 自动采集事件新增APP安装事件
• 优化属性检测逻辑：当字符串类型的数据超出2048字节时，会自动截断并上传
• 优化日志打印，更方便集成阶段的埋点测试
• 针对提升SDK稳定性和运行效率的其他代码优化
• minSdkVersion 升到 14

v1.3.0 2019/06/18

• 新增多APPID实例功能
• 新增动态公共属性特性
• 自动采集事件新增APP崩溃事件
• 稳定性提升：适配 Android Q、去除非必须的权限申请、优化运营商获取逻辑、支持 5G 等

v1.2.0 2019/05/23

• 支持 H5 与 APP 打通
• 支持 androidx （需配合自动采集插件 1.2.0 之后的版本）
• 优化部分代码逻辑

v1.1.7 2019/01/08

• 增加了上报数据的Log打印功能